Finding The Driver For A Device By Class

The USBGetNextDeviceByClass function returns a class driver reference for the class driver matching the specified device class and optionally the device subclass for that device. This function also works with interface references.

OSStatus USBGetNextDeviceByClass (
                     USBDeviceRef *deviceRef,
                     CFragConnectionID *connID,
                     UInt16 theClass,
                     UInt16 theSubClass,
                     UInt16 theProtocol);

<--> deviceRef

A pointer to the device or interface driver reference for the device or interface class specified.

<-- connID

A pointer to the device connection ID.

--> theClass

A number representing the device or interface class for which you want a compatible class driver. You can pass in kUSBAnyClass as a wildcard value. See the USB Specification for the device and interface class descriptions and identifiers.

--> theSubClass

A number representing the device or interface sub class for which you want a compatible class driver. You can pass in kUSBAnySubClass as a wildcard value. See the USB Specification for the device and interface subclass descriptions and identifiers.

--> theProtocol

A number representing the device or interface protocol for which you want a compatible class driver. You can pass in kUSBAnyProtocol as a wildcard value. See the USB Specification for the device and interface protocol descriptions and identifiers.

The USBGetNextDeviceByClass function returns a pointer to the next usbDeviceRef for a class driver matching the specified deviceClass and (optionally) deviceSubClass and deviceProtocol parameters. Pass kNoDeviceRef for the deviceRef parameter to begin, then pass the returned device reference for subsequent searches.

An OSStatus error of -43 is returned if a device cannot be found with the specified parameters. The device reference, deviceRef , returns unchanged if no subsequent match is made. The typical way to find all similar devices is to keep calling the USBGetNextDeviceByClass function until the status value changes from noErr . At that point, the deviceRef is officially undefined.

The driver descriptor structure must have the same class and subclass codes as the codes for the device that is specified in the function call. This is particularly important for vendor specific devices, since the correct driver for the device would not typically load if the class and subclass codes don't match those for the device.

If you are developing a device and the USBGetNextDeviceByClass function isn't finding the requested device, be sure that the driver descriptor structure for your device driver has the same class and subclass codes as the device.

Constants are defined for the device class, subclass, protocol, vendor, and product identifiers which you can pass as wildcard values in the functions USBGetNextDeviceByClass and USBInstallDeviceNotification Installing The Device Callback Request .

Constant	Value	Description
`kUSBAnyClass`	`0xffff`	Pass in as a wildcard in the `deviceClass` parameter or `usbClass` field in the device notification parameter block.
`kUSBAnySubClass`	`0xffff`	Pass in as a wildcard in the `deviceSubClass` parameter or `usbSubClass` field in the device notification parameter block
`kUSBAnyProtocol`	`0xffff`	Pass in as a wildcard in the `deviceProtocol` parameter or `usbProtocol` field in the device notification parameter block
`kUSBAnyVendor`	`0xffff`	Pass in as a wildcard in the `usbVendor` field in the device notification parameter block.
`kUSBAnyClass`	`0xffff`	Pass in as a wildcard in the `usbProduct` field in the device notification parameter block

Constant

Value

Description

kUSBAnyClass

0xffff

Pass in as a wildcard in the deviceClass parameter or usbClass field in the device notification parameter block.

kUSBAnySubClass

0xffff

Pass in as a wildcard in the deviceSubClass parameter or usbSubClass field in the device notification parameter block

kUSBAnyProtocol

0xffff

Pass in as a wildcard in the deviceProtocol parameter or usbProtocol field in the device notification parameter block

kUSBAnyVendor

0xffff

Pass in as a wildcard in the usbVendor field in the device notification parameter block.

kUSBAnyClass

0xffff

Pass in as a wildcard in the usbProduct field in the device notification parameter block

Note

In USB version 1.0.1 (the iMac update 1.0) a bug prevented correct searches if usbClass , usbSubclass , and usbProtocol were equal 0 and kNoDeviceRef is used for the deviceRef . This behavior is not present in version 1.1 and greater of the Mac OS USB software.